<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="resource-type" content="document">
<meta name="description" content="Porting guide: autoconf">
<meta name="keywords" content="openbsd,ports,autoconf">
<meta name="distribution" content="global">
<meta name="copyright" content="This document copyright 2004 by OpenBSD.">
<title>Porters' handbook: autoconf</title>
</head>
<body>
<img height="30" width="141" src="../images/smalltitle.gif" alt="[OpenBSD]"> 
<h1>Porters handbook: autoconf</h1>

Autoconf is a gnu tool that is supposed to help in writing portable programs.
It is often used together with automake (portable makefiles) and libtool
(portable shared libraries).
</p>
Those tools do not work all that well, and often set specific challenges
in porting software to OpenBSD.
</p>
<h2>Detecting the use of autoconf in a piece of software</h2>
Quite a few software projects have configure scripts, and in most cases,
those scripts were generated by autoconf.  Such scripts have a line near
the top that says:
<pre>
# Generated automatically using autoconf version 2.13 
</pre>
or something similar.
The generation procedure is covered in a following section. Most often,
autoconf ports come with the generated scripts, and with the source scripts
that generated these.  The next section covers the simple case where you simply
want to run the generated script, and not modify it.
Make sure you read the section about Trojan horses as well.
<h2>Running an autoconf configure script</h2>
This script is normally run during the configure stage of ports building.
To invoke the configure script, one only has to set
<code>CONFIGURE_STYLE=	gnu</code>
which will automatically invoke ${WRKSRC}/configure.
</p>
If your configure script lies elsewhere, just set CONFIGURE_SCRIPT to the
right value.
</p>
Configure scripts often take a lot of arguments. The default processing of 
the ports tree will only pass --prefix and --sysconfdir to these.
Very old configure scripts don't understand --sysconfdir; you can set
<code>CONFIGURE_STYLE=gnu old</code> in such cases.
</p>
Similarly, some ports are not aware of DESTDIR.  Those ports will often
accept setting 
<code>prefix=${DESTDIR}/usr/local</code>
without any issue, which can be
done with <code>CONFIGURE_STYLE=gnu dest</code>.
</p>
Ports using autoconf and automake will have Makefiles with a specific format,
that begins with a few standard locations:
<ul>
<li>bindir: location for binaries
<li>sysconfdir: location for configuration
<li>includedir: location for include dirs
</ul>
If the configure script does not allow you to override these, you may still be able to do it later on during the build or fake stage.  This does assume, of course, that the only reference to such a directory is within the generated Makefile.
</p>
For instance, a neat trick involves switching sysconfdir to ${LOCALBASE}/share/example/pkgname during the fake stage, to get default config files to package
(since packages don't normally store stuff under /etc).
</p>
Ports fully using autoconf and automake   may support building under
a different directory: try setting
<code>SEPARATE_BUILD=flavored</code>
and see if that works.  This would allow you to wipe the build tree without
wiping the source tree, by giving you separate ${WRKSRC} and
${WRKBUILD} locations.  In a few cases, separate builds may need to
use gmake, where the rest of the port is happy with bsd-make,
in which case this is not worth it.
</p>
automake will generate a few rules to rebuild all the generated scripts if anything changes. These often get in the way of OpenBSD specific patches. For that reason, as soon as CONFIGURE_STYLE corresponds to autoconf use, post-patch will touch various files in a specific order, so that no automake dependencies get triggered later.
The list of dependencies is given in tsort(1) order in a file mentioned in
REORDER_DEPENDENCIES (the default is
${PORTSDIR}/infrastructure/mk/automake.dep).
<h2>The mechanics of configure checks</h2>
The configure script first runs a fixed script called config.guess, 
that will determine which system configure is running on.  config.guess 
does not vary from port to port and is a fixed script, so
the OpenBSD ports tree replaces it with a fixed version that knows about some
specific OpenBSD architectures.  Since most software packages come with bundled
config.guess, and since some of them are quite old, this is a necessary step.
If a software package contains more than one config.guess, you can overwrite
them all by setting MODGNU_CONFIG_GUESS_DIRS to the full list of directories
to process.
</p>
The configure script generated by autoconf then  simply checks all functionality
on the existing system, by looking for a compiler, and running simple test
programs through it.  Since some of these tests are quite lengthy, the ports
tree primes configure with a CONFIG_SITE=config.site file.
configure will look at the contents of that file first before running the tests.
A few configure scripts may have bugs that will prevent them from running correctly in the presence of config.site. Setting CONFIG_SITE to empty will weed out
these kind of problems.
</p>
Most configure will auto-detect quite a few conditions. It is very important to look at configure's options, at configure's output, and at the generated config.log file: these will tell you what options were found, and what options were not found.  This will allow you to find out when configure did not find a package that was installed.  
</p>
This will also tell you which optional packages configure would find. In the ports tree, those are called hidden dependencies.  This is a bad thing: a hidden dependency is some extra package configure will pick up if it's installed. Then it will proceed in building a mutant package. In some cases, the build will fail because of OpenBSD peculiarities. In some cases, the package creation will fail, as some files will have different names. In some cases, the resulting package will be incorrect, as it will fail to record any dependency on the optional package.   So looking at configure's output is one of the most important duty of ports' maintainers.   Watch out for cascading tests: detecting a given feature may lead a configure script to try out and find some dependent feature, so you will not see the second feature in the configure output unless the first feature is triggered.
</p>
In case some hidden dependencies are found, some action should be taken. The most simple action is to install the optional package, and see what configure will do. If it detects the package, one can either disable the detection (by using configure options, or environment variables, or patching the configure script),
or verify that the build goes well and add the dependency to the list of dependent packages.  A better choice is to figure out a reasonable set of default dependencies, and then add some flavors to cover other common features.
<h2>Re-generating configure scripts</h2>
Configure scripts are normally generated from a configure.in file (recent versions of autoconf use a configure.ac file instead). A standard library of definitions is often available in an aclocal.m4.
</p>
In most cases, patching configure directly is a bad idea.  It is better to patch the configure.in file and get the ports tree to call autoconf.   Good porters will endeavor to write configure.in changes that they can feed to software authors.
</p>
Different versions of autoconf will produce distinct configure scripts. 
autoconf-2.13 is special: it was used over a fairly long period, and there has been mutant versions of autoconf-2.13 (actually, betas of a newer autoconf) in wide use.  Hence, using autoconf-2.13 will often not produce the exact same configure script.
</p>
Since having several autoconf versions around at the same time is useful, the autoconf script actually available in the ports tree is part of a port called metaauto.  Which autoconf script actually gets called is controlled through the environment variable AUTOCONF_VERSION.
Calling autoconf happens if you set CONFIGURE_STYLE=autoconf, together with
setting AUTOCONF_VERSION.  Versions currently available are 2.13, 2.52, 2.54,
2.56, 2.57, 2.58, and 2.59. These cover 99% of all configure scripts out there.
</p>
autoconf relies on the standard unix preprocessor m4(1).  Normally, autoconf relies on some features on the GNU version of m4, gm4.  Fortunately, OpenBSD's m4
has enough features to run autoconf as well, it just needs to be invoked with -g to handle autoconf.   Very seldom, autoconf run with OpenBSD's m4 will produce bogus configure scripts.   The OpenBSD developers will fix such an issue.
<h2>Trojan horses</h2>
Configure scripts are big generated files.  They are an ideal hiding place
for Trojan horses, and this has indeed already happened in the past.
This is the main reason for having most versions of autoconf in the tree:
a good porter is expected to check that a generated configure script matches
what the ports tree autoconf builds.
<h2>Interaction with other programs</h2>
autoheader is another program related to autoconf that is normally run to
create a config.h.in file.  Setting CONFIGURE_STYLE=autoconf will also run
autoheader. A few ports don't use autoheader. Setting CONFIGURE_STYLE=autoconf no-autoheader will fix that issue.
</p>
libtool has a few specific hooks in configure.in.  There is often a 
libtool.m4 script that goes with it.   Getting libtool to do the right thing
goes beyond the scope of this documentation.
</p>
KDE uses an extra layer on top of autoconf. This extra layer assembles a
configure.in file from a set of configure.in.in files, and is also able to
tweak both configure.in for snappier results, and Makefile.in to allow for
some supplementary options in building, and to automatically insert DESTDIR
in the right places.
The AUTOCONF variable can be used to tweak the actual autoconf script
that gets run, and KDE expects /bin/sh ${WRKDIST}/admin/cvs.sh to work
correctly.
  <hr>
  <a href="../index.html"><img height=24 width=24 src=../back.gif border=0 alt=OpenBSD></a> 
  <a href="mailto:www@openbsd.org">www@openbsd.org</a>
<br><small>$OpenBSD: autoconf.html,v 1.4 2005/01/21 11:08:53 alek Exp $</small>
 </body>
</html>
